feat(model-groups): surface effective modalities and fail early on spawn (issue #26) - #27

# Conflicts:
#	tests/unit/spawn.test.ts

…bel, stale editor, prose single-source

- store: strip runtime-derived keys (name/scope/sourcePath/modalities/validation)
  at the persistence boundary; opaque user keys + modalityOverride preserved
- tui: draft projection persists only models/override; MODALITIES editor choices
  union supported + stale override members; empty effective labels unambiguous
- index: empty effective renders '(no common modalities)' instead of '(none)'
- prose vocab single-sourced from MODEL_GROUP_MODALITIES (spawn + prompt section)
- router: documented absent == empty requiredModalities semantics

Resolve the pluggability gap with a typed, compile-time constraint
registry + generic envelopes, absorbed into PR agenticoding#27 (unmerged-v2, no
migration; version stays 2).

- constraints/: pure generic kernel (engine/registry/resolution/presentation)
  with injectable registries; production registers only modalities.
- Modality constraint descriptor owns extraction, aggregation,
  reconciliation, requirements, diagnostics, presentation, editor;
  model-groups/modalities.ts becomes thin compatibility façades (parity).
- Persisted envelope: ModelGroupDef.constraints (canonical) +
  modalityOverride (conflict-safe deprecated alias; equal coalesces,
  unequal rejects; unknown slots round-trip opaquely).
- Spawn envelope: constraints (descriptor-generated TypeBox) +
  requiredModalities alias, normalized at one boundary pre-route.
- Router: iterates registry descriptors; modality violations keep the
  exact missing-modality SpawnRouteError arrays; injected scalar routes
  to additive constraint-unsatisfied.
- Prompt/boot-summary/TUI iterate descriptor presentation metadata;
  notification text and (no common modalities) fallback byte-identical.
- AC6 proof: synthetic testMinContext descriptor traverses the full seam
  via router + registered spawn (0 factory calls, both maps empty);
  production registry stays [modalities], no production testMinContext.

Refactor-only: no materialized cost/context/param dimension.

Full battery green: typecheck, unit 669/669, e2e 16/16, snapshots 11/11,
compat:current 0.84.2, package-host, git diff --check.

…th thinking effort

Per operator ADJ-001 tweaks:
- Move modality markers out of the select label into the description column,
  aligned with the thinking-effort segment (same inline position).
- Use single colored letters per modality instead of full words: T=text,
  I=image, R=reasoning.
- Recolor text modality from accent (teal) to syntaxKeyword (blue) so it no
  longer collides with the selected-row highlight, which also wraps in accent.
- Legend now reads 'modalities: T text · I image · R reasoning' with colored
  letters. Each description segment re-asserts dim after inner colored spans
  so the surrounding dim survives the fg reset (fg resets to terminal default).
- Update unit test to scope single-letter assertions to the review row.

… modalities UI

ADJ-002 (approved) + option A:
- Replace the power-set enumeration in the MODALITIES screen with an
  Automatic row (reset; [✓] while default) + one toggle row per media
  modality (text/image). Enter on a toggle flips that modality in/out,
  seeding from the current effective set on the first toggle so an
  automatic group transitions to an explicit override smoothly.
- New ConstraintEditorRow kind 'toggle' in constraints/presentation.ts;
  multi-select rows now enumerate automatic + one toggle per choice
  instead of the 2^n subset list. Activation builds the next override
  (vocab-ordered) from effective plus/minus the pressed modality.
- Reasoning is a distinct pre-existing capability (per-member thinkingLevel
  + routing gate), so it is excluded from the modality presentation: the
  MODALITIES screen rows, the list legend/chips, and the EDITOR summary
  lines all show only text/image. Kernel/schema/router unchanged; any
  persisted reasoning override value is preserved (never clobbered).
- Add generic multi-select editor-shape test; re-baseline the TUI modal
  editor commit test to toggle individual modalities.

ADJ-002 follow-up:
- Enter on a modality toggle (or the Automatic reset) now persists the change
  and STAYS on the MODALITIES screen so the user can keep toggling, instead of
  bouncing back to the group editor. Esc still closes back to the editor.
- Space key now toggles the selected modality as well as Enter (both dispatch
  to activate on the MODALITIES screen).
- Add a dim hint line: 'up/down navigate • Enter/Space toggle • Esc close'.
- Refactor updateDraft into persistDraft (persist + refresh + re-resolve, no
  navigation) + updateDraft (navigates on success). The MODALITIES toggle uses
  persistDraft and re-binds the edit draft to the refreshed group. Preserves
  original stay-put-on-error semantics (afterSuccess only runs on success).
- Tests: rework commit test to assert stay-on-screen + Esc exit; add a Space
  toggle test.

Make text a structurally guaranteed base capability (matching the invariant
that image/reasoning both imply text). reconcile now always keeps text in the
effective set whenever the group supports it, regardless of override. This
eliminates the empty-group asymmetry: deselecting every modality now yields a
text-only group (effective=[text]) rather than effective=[] that let text
spawns through while denying image/reasoning.

MODALITIES screen becomes thin: a fixed non-selectable 'text [always]' line
plus the Automatic reset and toggles for additive capabilities only (image;
reasoning stays per-model via thinkingLevel, text is the base).

Tests: update unresolved-member and override-effective expectations to include
always-present text; add a backstop-invariant test; adjust TUI text-row
assertion to '[always]'.

Modality-specific usability follow-up only (from #planner UX review); general
TUI debt left untouched and tracked separately.

- MODALITIES screen title now names the group: 'Modalities — <name>' instead
  of the bare 'MODALITIES'.
- Fix hint wording: 'Esc close' -> 'Esc back', 'Enter/Space toggle' ->
  'Enter/Space apply' (the Automatic row resets rather than toggles).
- Static text row: align with selectable rows and reword '[always]' ->
  'required base' so it describes the invariant without claiming an
  empty/all-unavailable group is usable.
- EDITOR modality line: drop 'Common:' jargon -> 'Supported by every model:'.
- Descriptor automatic label: 'Automatic (common: X)' -> 'Automatic (X)'
  (the 'common:' vocabulary was redundant; text is now the always-present
  base via the kernel invariant).
- Update TUI + constraints test expectations for the new wording/labels.

…odels in editor

(#code-review design) Give the group editor two compact static section bars so
the modalities config reads as its own stand-alone block distinct from the
model membership:

  Model Group: review
    Location: project / global
    Name: review
  -- Capabilities --
    Supported by every model: text
    Modalities: Automatic (text, image)
  -- Models --
    provider/model (available, thinking X)
    + Add model...

- 'Capabilities' bar groups the group-level modality policy ('Supported by
  every model' + the Modalities action).
- 'Models' bar heads the member list/Add row.
- Bars and the 'Supported by every model' line are static/non-selectable, so
  all logical row indices and Enter targets are unchanged (only visual bars
  added; zero keyboard rework).
- Automatic/Override now capitalized in the editor summary line.
- Theme discipline kept: dim rules, accent labels, no bare ANSI, no chips in
  the editor (full names are more legible here; LIST chips/legend unchanged),
  MODALITIES screen + constraint kernel untouched.
- Update editor test assertions (Override/Automatic casing, add Capabilities/
  Models coverage).

…ete (ADJ-005)

Share the modality letter/color lexicon in model-groups/modality.ts and have the
#-mention suggestion tooltip prepend each group's effective media-modality letters
(T=text I=image, reasoning excluded) via a lazy ctx.ui.theme colorizer, keeping the
trigger/value/label and per-model route details intact.

…-005)

Pad the effective media-modality letter column to a shared width across the
visible suggestion rows so per-model route details start at the same column,
instead of variable-offset text that can cut into the capability column.

… (ADJ-005)

Image presence implies text, so the #-mentions show a single capability letter
(OpenRouter-style): text-only groups keep T, image-bearing groups show only I.
Shared modalityLetterRun gains hideTextWhenOtherMedia; the model list rows keep
the full T/I lexicon.

When a routed group carries an explicit modality override that excludes image,
the spawned child prompt now includes a Model Group capability ceiling notice
telling it to report a capability mismatch rather than silently work around it
(e.g. reading an image). The router exposes the override ceiling on the route
regardless of whether the caller declared a requirement. Advisory only: no
enforcement or model-input stripping yet (operator will test-drive before
extending scope).

When the operator explicitly names a specific model group (e.g. #quick-review)
and the task requires a capability that group lacks, the parent must NOT
substitute a different group, inherit the parent model, or work around the
missing capability. It stops and reports the mismatch, asking whether to pick a
different group or drop the capability. Aligns the system-prompt model-groups
guidance (index.ts modelGroupsPromptSection) with the spawn tool prompt
guidelines (spawn/index.ts SPAWN_PROMPT_GUIDELINES).

… picker chips (D2)

D1: when a #group spawn declares a modality requirement, resolveSpawnModelRoute now narrows the selection pool to members whose individual modality fact satisfies it, and round-robins across that capable set via an in-memory session cursor (state.spawnRouteCursors) instead of uniform random over all usable members. Unauthenticated models and non-capable members are excluded; overridden group ceilings still govern and wholly-incapable groups still reject missing-modality.

D2: the Add-model picker (WIZARD_MODEL) now renders a per-model colored T/I capability chip by reusing the shared modality lexicon and getModalitiesModelFact, so capability is visible while adding.

…the union

Automatic (no-override) groups now expose the union of their members'
individual modality facts as the effective capability set, instead of the
intersection. This fixes a real routing gate bug: an Automatic mixed group
[text, text+image] with an image spawn selected the image-capable member via
D1 pre-selection, but the group gate then saw effective=common=[text] and
rejected a missingFromGroup=image.

An explicit persisted override remains an authoritative subtractive ceiling
(text always present; filtered to each member's supported list), preserving
ADJ-005 Policy B and the named-group 'stops + reports' contract (e.g.
quick-review [text, reasoning] still rejects image spawns). common stays the
factual every-member editor field; only the reconcile default changes.

Battery: unit 688, snapshots 11, e2e 16, compat 16, package-host, audit-ci.

…ited modalities guidance

Model rows in the editor now render the same colored T/I chips as the
Add-model picker (D2), derived per-member from getModalitiesModelFact;
unresolved members render without a chip. The modalities hand-edit screen
gains two short dim guidance lines explaining Automatic (uses every
capability its members support) vs Override (limited to exactly the listed
capabilities) — the D3 union-default vs subtractive-ceiling semantics.

The modalities hand-edit screen drops the Automatic selector row and is now
built around disabling capabilities from the available union set:

  T text  [required]
→ I image  [off]

- Text is a non-toggleable required base row (always [required], matching the
  operator decision that text is present whenever any model is added).
- The remaining union media capabilities are [on]/[off] toggles.
- Toggling OFF a capability writes a subtractive override from the current
  effective (preserving hidden reasoning ceilings, e.g. image off on
  [text,image,reasoning] stores [text,reasoning]).
- Toggling the last capability back ON collapses to Automatic only when the
  ordered candidate equals the full union — so no override (and no spawn
  ceiling) is stored for a non-limit; entering Automatic remains fully
  reachable even without a selector row.
- A single dynamic status line replaces the two static guidance lines:
  'Automatic — using every capability its members support.' vs
  'Override — media limited to <media>.'
- Zero-toggle screens (text-only) show 'No optional media capabilities
  available.' + 'Esc back'; Enter/Space are inert.

Generic constraintEditorRows() and its constraint-layer test are unchanged;
only the TUI screen specializes. Tests updated for the new interaction
(override commit, re-enable-to-Automatic collapse, failure notify, dynamic
status) plus a new text-only inert-screen test. Battery: unit 690, snapshots
11, e2e 16, compat, package-host.

…t highlight

Per planner-design + operator calls:

- The per-row '— Enter/Space toggles' hint is removed (was noise on the typical
  T+I vocabulary).
- Single editable row screens drop '↑↓ navigate' — the footer is just
  'Enter/Space toggle • Esc back' (arrow-nav returns only if a second visible
  media row ever appears).
- The selected capability row is now accent-highlighted: accent arrow + accent
  label while the modality letter keeps its own color. Previously the
  selectableLine accent wrap was neutralized by inner color resets, so the
  row appeared unhighlighted.
- Text-only screens keep 'No optional media capabilities available.' + 'Esc back'
  with Enter/Space inert.

Tests: hint assertions replaced by compact-footer assertions; accent-token test
extended to MODALITIES asserting the highlight markup; width-bounded test
comment corrected (the assertion after the name row is MODALITIES, not
MODEL_EDIT). Battery: unit 690, snapshots 11, e2e 16, compat, package-host.

…ing#27)

- V2-A-01: fully-stale non-empty modality override falls back to derived
  union; explicit [] override stays text-only; subtractive ceiling kept
- V2-B-02: TUI cloneDef preserves opaque top-level group keys on edit
- V1-01: trim trailing whitespace in modalities diagnostic
- V2-B-01/V1-03: low-level save is shape-only, CRUD rejects union-cap
  invalid overrides; boundary locked by test
- V1-04: malformed legacy v1 modalityOverride loads opaquely, drops on v2
- V3-A-02: generic descriptor selection + descriptor-owned ceiling
  advisories (no image literal in spawn)
- test-only synthetic min-context and max-budget descriptors prove the
  capability-generic seam; production registry stays exactly {modalities}

Battery: typecheck, npm test 695/695, e2e 16/16, snapshots 11/11,
compat 166/166, package-host, audit-ci, git diff --check

…agenticoding#27)

- N-27-1: cursor round-robin engages only when declared requirements genuinely
  narrow the pool (capable < usable); routed empty {required:[]} returns to
  uniform RNG (regression fixed + routed test)
- F2-3: reset invariant now populates and asserts spawnRouteCursors cleared
- F2-2: spawn tool constraints schema built from the registry passed at
  registration (injected/test descriptors accepted at tool-schema level);
  whole-path test validates through real registered schema, not direct execute
- D-7: removed dead descriptor fields (persistence.clone, editor.format,
  editor.allowAutomatic); single-sourced MODEL_GROUP_MODALITY_PROSE; corrected
  reasoning-doc default
- readability: split modalities.ts nested ternary into explicit four cases

F2-1 (downgrade data-loss) intentionally left open per operator.
Battery: typecheck, npm test 697/697, e2e 16/16, snapshots 11/11, compat
167/167, package-host, audit-ci, git diff --check.

Split the single-line field declarations + nested-ternary message builder
into a documented class with one field per line, an explicit details
interface, and a branch-based describeRouteError helper. Public surface
(reason/group/missing*/constraintUnsatisfied/message strings) is unchanged
and asserted by existing router + spawn tests.

Battery: typecheck, unit 697/697, e2e 16/16, snapshots 11/11, compat
167/167, package-host, audit-ci, git diff --check.

…re/tui/types

Structure-only readability pass (no logic change, no new behavior):
- router: expand effectiveGroupMap loop, resolveSpawnModelRoute setup/pool/
  cursor/route construction, and modality-error extraction into named locals
- store: split backups, loadScope, mergeLoaded, normalizeGroups, saveModelGroups,
  CRUD (create/update/rename/delete/move), validateModelGroups into readable
  multi-line form; preserved error-wrapping order and phases
- tui: bind MODEL_EDIT lookup + decompose renderEditorComponent nested chain
- types: expand ModelGroupsPersistenceError ctor

Independent review caught and I fixed one real delta introduced mid-refactor:
moveGroup source-removal failure rewrap reported newScope path; restored to
oldScope sourcePath. F2-1 downgrade guard deliberately NOT added (store.ts
semantics unchanged).

Battery: typecheck, unit 697/697, e2e 16/16, snapshots 11/11, compat 167/167,
package-host, audit-ci, git diff --check.

Extract cohesive helpers (decodeDeclared, inheritedRoute, usableMembers,
selectMember, buildRoutedRoute, attachCeilings, collectViolations,
raiseRouteFailure) so the routing function drops from ~43 decision points to
~7. Stictly behavior-preserving: cursor round-robin semantics, capable-pool
fallback, RNG clamp, error taxonomy/messages, and empty-requirements guard
are unchanged and lock-blocked by the existing router + spawn suites.

Battery: typecheck, unit 697/697, e2e 16/16, snapshots 11/11, compat 167/167,
package-host, audit-ci, git diff --check.